ECS Mandate Classifier API

The following document highlights the details of the ECS Mandate Classifier API.

API Description

Objective

The ECS Mandate Classifier API classifies a PDF or image as either an ECS Mandate or a different type of document.

Input	Output
An image or a PDF	The result indicating whether the document provided is an ECS Mandate or some other document

info

An ECS (Electronic Clearing Service) mandate is an authorization form that allows a bank to automatically debit or credit a customer's account for recurring payments. It essentially gives a user institution (like a lender or service provider) permission to make electronic transfers on a regular basis without manual intervention.

API URL

https://ind-engine.thomas.hyperverge.co/v1/readECSClass

API Endpoint

readECSClass

Overview

The ECS Mandate Classifier API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the ECS Mandate Classifier API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the ECS Mandate Classifier API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
image	Mandatory	file	The input PDF or image file on which the classification is to be performed	Image file (JPEG, JPG, PNG) or PDF	Not Applicable

Caution

• If multiple images are sent to the server in the same call, only one of the images will be read. Hence it is advisable to only send one image per call.
• If the PDF file has multiple pages, only the first page will be considered for the OCR extraction.

Request

The following code snippet demonstrates a standard curl request for the ECS Mandate Classifier API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/readECSClass' \
--header 'appid: <Enter_the_appId-Shared-by-HyperVerge>' \
--header 'appkey: <Enter_the_appKey-shared-by-HyperVerge>' \
--header 'transactionId : <Enter_the_Transaction_ID>' \
--form 'image=@"<path_to_image_file>"'

Success Response

The following code snippet demonstrates a success response from the ECS Mandate Classifier API:

Document Classified: ECS Mandate

{
  "status": "success",
  "statusCode": 200,
  "result": {
        "type": "ECS Mandate"
      },
    "metadata": {
        "requestId": "<Request_ID>"
      }
    }

Document Classified: Other Document

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "type": "OTHER"
  },
    "metadata": {
        "requestId": "<Request_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the ECS Mandate Classifier API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned for the request
result	object	Contains the classification result
type	string	The classification result indicating whether the document is an ECS Mandate or another type
metadata	object	Contains request and transaction identifiers
requestId	string	A unique identifier for the request

Failure Response

The following code snippet demonstrates a failure response from the ECS Mandate Classifier API:

{
  "status": "failure",
  "statusCode": 400,
  "error": "API call requires one input image"
}

Error Responses

The following are some error responses from the ECS Mandate Classifier API:

No Image Input

{
    "status": "failure",
    "statusCode": 400,
    "error": "API call requires one input image"
}

Image Size Exceeds Limit of 6MB

{
    "status": "failure",
    "statusCode": 400,
    "error": "Image size cannot be greater than 6MB"
}

Document Not Detected

{
    "status": "failure",
    "statusCode": 422,
    "error": "Document Not Detected"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	API call requires one input image	The request does not include an input image, which is mandatory for processing.	Ensure the request includes the image parameter with a valid image or PDF file
400	Image size cannot be greater than 6MB	The provided image exceeds the maximum allowed size of 6MB.	Reduce the image file size to 6MB or less before submitting the request
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
422	Document Not Detected	The system was unable to detect any document in the provided image.	Ensure the image contains a clear and visible ECS Mandate document, or contact the HyperVerge team if the issue persists
500	Internal Server Error	There was an error with HyperVerge's server	Please check the request headers or contact the HyperVerge team for resolution